SGI Performance Co-Pilot 1.3/SGI Performance Co-Pilot 1.3.iso/dist/pcp.idb/usr/share/catman/u_man/cat1/pmlogger.z.z/pmlogger.z/pmlogger

Text File | 1997-04-03 | 26KB | 393 lines

PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR((((1111))))                                                        PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR((((1111))))



NNNNAAAAMMMMEEEE
     ppppmmmmllllooooggggggggeeeerrrr - create archive log for performance metrics

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     ////uuuussssrrrr////ppppccccpppp////bbbbiiiinnnn////ppppmmmmllllooooggggggggeeeerrrr [----PPPP] [----cccc _c_o_n_f_i_g_f_i_l_e] [----hhhh _h_o_s_t] [----llll _l_o_g_f_i_l_e] [----LLLL]
     [----nnnn _n_a_m_e_s_p_a_c_e] [----ssss _s_a_m_p_l_e_s] [----TTTT _r_u_n_t_i_m_e] [----vvvv _v_o_l_s_a_m_p_l_e_s] _a_r_c_h_i_v_e

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     ppppmmmmllllooooggggggggeeeerrrr creates the archive logs of performance metric values that may
     be ``played back'' by other Performance Co-Pilot (PCP) tools.  These logs
     form the basis of the VCR paradigm and retrospective performance analysis
     services common to the PCP toolkit.

     The mandatory argument _a_r_c_h_i_v_e is the base name for the physical files
     that constitute an archive log.

     Unless directed to another host by the ----hhhh option, ppppmmmmllllooooggggggggeeeerrrr will contact
     the Performance Metrics Collector Daemon (PMCD) on the local host and use
     that as the source of the metric values to be logged.

     To support the required flexibility and control over what is logged and
     when, ppppmmmmllllooooggggggggeeeerrrr maintains an independent two level logging state for each
     instance of each performance metric.  At the first (mandatory) level,
     logging is allowed to be oooonnnn (with an associated interval between
     samples), or ooooffffffff or mmmmaaaayyyybbbbeeee.  In the latter case, the second (advisory)
     level logging is allowed to be oooonnnn (with an associated interval between
     samples), or ooooffffffff.

     The mandatory level allows universal specification that some metrics must
     be logged, or must nnnnooootttt be logged.  The default state for all instances of
     all metrics when ppppmmmmllllooooggggggggeeeerrrr starts is mandatory maybe and advisory off.

     Use ppppmmmmllllcccc(1) to interrogate and change the logging state once ppppmmmmllllooooggggggggeeeerrrr is
     running.

     If a metric's state is mandatory (on or off) and a request is made to
     change it to mandatory maybe, the new state is mandatory maybe and
     advisory off.  If a metric's state is already advisory (on or off) and a
     request is made to change it to mandatory maybe, the current state is
     retained.

     It is not possible for ppppmmmmllllooooggggggggeeeerrrr to log specific instances of a metric and
     all instances of the same metric concurrently.  If specific instances are
     being logged and a request to log all instances is made, then all
     instances of the metric will be logged according to the new request,
     superseding any prior logging request for the metric.  A request to log
     all instances of a metric will supersede any previous request to log all
     instances.  A request to log specific instances of a metric when all
     instances are already being logged is refused.  To do this one must turn
     off logging for all instances of the metric first.  In each case, the
     validity of the request is checked first; for example a request to change
     a metric's logging state to advisory on when it is currently mandatory



                                                                        PPPPaaaaggggeeee 1111






PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR((((1111))))                                                        PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR((((1111))))



     off is never permitted (it is necessary to change the state to mandatory
     maybe first).

     Optionally, each system running ppppmmmmccccdddd(1) may also be configured to run a
     ``primary'' ppppmmmmllllooooggggggggeeeerrrr instance.  Like ppppmmmmccccdddd(1), this ppppmmmmllllooooggggggggeeeerrrr instance is
     launched by ////eeeettttcccc////iiiinnnniiiitttt....dddd////ppppccccpppp, and is affected by the files
     /_e_t_c/_c_o_n_f_i_g/_p_m_l_o_g_g_e_r (use cccchhhhkkkkccccoooonnnnffffiiiigggg(1M) to activate or disable the
     primary ppppmmmmllllooooggggggggeeeerrrr instance), /_e_t_c/_c_o_n_f_i_g/_p_m_l_o_g_g_e_r._o_p_t_i_o_n_s (command line
     options passed to the primary ppppmmmmllllooooggggggggeeeerrrr) and
     /_v_a_r/_p_c_p/_c_o_n_f_i_g/_p_m_l_o_g_g_e_r/_c_o_n_f_i_g._d_e_f_a_u_l_t (the default initial
     configuration file for the primary ppppmmmmllllooooggggggggeeeerrrr).

     The primary ppppmmmmllllooooggggggggeeeerrrr instance is identified by the ----PPPP option.  There may
     be at most one ``primary'' ppppmmmmllllooooggggggggeeeerrrr instance on each system with an
     active ppppmmmmccccdddd(1).  The primary ppppmmmmllllooooggggggggeeeerrrr instance (if any) must be running
     on the same host as the ppppmmmmccccdddd(1) to which it connects, so the ----hhhh and ----PPPP
     options are mutually exclusive.

     When launched as a non-primary instance, ppppmmmmllllooooggggggggeeeerrrr will exit immediately
     if the configuration file causes no metric logging to be scheduled.  The
     ----LLLL option over-rides this behaviour, and causes a non-primary ppppmmmmllllooooggggggggeeeerrrr
     instance to ``linger'', presumably pending some future dynamic re-
     configuration and state change via ppppmmmmllllcccc(1).

     By default all diagnostics and errors from ppppmmmmllllooooggggggggeeeerrrr are written to the
     file _p_m_l_o_g_g_e_r._l_o_g in the directory where ppppmmmmllllooooggggggggeeeerrrr is launched.  The ----llll
     option may be used to over-ride the default behavior.  If the log file
     cannot be created or is not writable, output is written to standard error
     instead.

     If specified, the ----ssss option instructs ppppmmmmllllooooggggggggeeeerrrr to terminate after _s_a_m_p_l_e_s
     records have been written to the log.  The default is for ppppmmmmllllooooggggggggeeeerrrr to run
     forever.

     The log file is potentially a multi-volume data set, and the ----vvvv option
     causes ppppmmmmllllooooggggggggeeeerrrr to start a new volume after _v_o_l_s_a_m_p_l_e_s records have been
     written to the log.  The default is for ppppmmmmllllooooggggggggeeeerrrr to create a single
     volume log.  Additional volume switches can also be forced asynchronously
     by either using ppppmmmmllllcccc(1) or sending ppppmmmmllllooooggggggggeeeerrrr a SIGHUP signal (see below).

     Normally ppppmmmmllllooooggggggggeeeerrrr operates with the default Performance Metrics Namespace
     (PMNS), however if the ----nnnn option is specified an alternative namespace is
     loaded from the file _n_a_m_e_s_p_a_c_e.

     Under normal circumstances, ppppmmmmllllooooggggggggeeeerrrr will run forever (or at least until
     it is terminated by most signals that can be caught).  The ----TTTT option may
     be used to limit the execution time to be no more than _r_u_n_t_i_m_e seconds,
     after which ppppmmmmllllooooggggggggeeeerrrr terminates in an orderly fashion.

     When ppppmmmmllllooooggggggggeeeerrrr receives a SIGHUP signal, the current volume of the log is
     closed, and a new volume is opened.  This mechanism (or the alternative
     mechanism via ppppmmmmllllcccc(1)) may be used to manage the growth of the log files



                                                                        PPPPaaaaggggeeee 2222






PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR((((1111))))                                                        PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR((((1111))))



     - once a log volume is closed, that file may be archived without ill-
     effect on the continued operation of ppppmmmmllllooooggggggggeeeerrrr.  See also the ----vvvv option
     above.

     The buffers for the current log may be flushed to disk using the fffflllluuuusssshhhh
     command of ppppmmmmllllcccc(1), or by sending ppppmmmmllllooooggggggggeeeerrrr a SIGUSR1 signal.  This is
     useful when the log needs to be read while ppppmmmmllllooooggggggggeeeerrrr is still running.

CCCCOOOONNNNFFFFIIIIGGGGUUUURRRRAAAATTTTIIIIOOOONNNN FFFFIIIILLLLEEEE SSSSYYYYNNNNTTTTAAAAXXXX
     The configuration file may be specified with the ----cccc option.  If it is
     not, configuration specifications are read from standard input.

     If _c_o_n_f_i_g_f_i_l_e does not exist, then a search is made in the directory
     /_v_a_r/_p_c_p/_c_o_n_f_i_g/_p_m_l_o_g_g_e_r for a file of the same name, and if found that
     file is used, e.g. if _c_o_n_f_i_g._m_u_m_b_l_e does not exist in the current
     directory and the file /_v_a_r/_p_c_p/_c_o_n_f_i_g/_p_m_l_o_g_g_e_r/_c_o_n_f_i_g._m_u_m_b_l_e does exist,
     then ----cccc ccccoooonnnnffffiiiigggg....mmmmuuuummmmbbbblllleeee and ----cccc ////vvvvaaaarrrr////ppppccccpppp////ccccoooonnnnffffiiiigggg////ppppmmmmllllooooggggggggeeeerrrr////ccccoooonnnnffffiiiigggg....mmmmuuuummmmbbbblllleeee are
     equivalent.

     The syntax for the configuration file is as follows.

     1.   Words are separated by white space (space, tab or newline).

     2.   The symbol ``#'' (hash) introduces a comment, and all text up to the
          next newline is ignored.

     3.   Keywords (shown in bbbboooolllldddd below) must appear literally (i.e. in
          lowercase).

     4.   Each specification begins with the optional keyword lllloooogggg, followed by
          one of the states mmmmaaaannnnddddaaaattttoooorrrryyyy oooonnnn, mmmmaaaannnnddddaaaattttoooorrrryyyy ooooffffffff, mmmmaaaannnnddddaaaattttoooorrrryyyy mmmmaaaayyyybbbbeeee,
          aaaaddddvvvviiiissssoooorrrryyyy oooonnnn or aaaaddddvvvviiiissssoooorrrryyyy ooooffffffff.

     5.   For the oooonnnn states, a logging interval must follow using the syntax
          ``oooonnnncccceeee'', or ``eeeevvvveeeerrrryyyy _N _t_i_m_e_u_n_i_t_s'', or simply ``_N _t_i_m_e_u_n_i_t_s'' - _N is
          an unsigned integer, and _t_i_m_e_u_n_i_t_s is one of the keywords mmmmsssseeeecccc,
          mmmmiiiilllllllliiiisssseeeeccccoooonnnndddd, sssseeeecccc, sssseeeeccccoooonnnndddd, mmmmiiiinnnn, mmmmiiiinnnnuuuutttteeee, hhhhoooouuuurrrr or the plural form of
          one of the above.
          Internal limitations require the interval to be smaller than
          (approximately) 74 hours.  An interval value of zero is a synonym
          for oooonnnncccceeee.

     6.   Following the state and possible interval specifications comes a
          ``{'', followed by a list of one or more metric names, and a closing
          ``}''.  The list is white space (or comma) separated, and the names
          are as per the standard PCP naming conventions, see ppppmmmmnnnnssss(4).  If
          there is only one metric name in the list, the braces are optional.
          If a metric name is a non-leaf node in the namespace (see ppppmmmmnnnnssss(4)),
          then ppppmmmmllllooooggggggggeeeerrrr will recursively descend the PMNS and apply the
          logging specification to all leaf nodes.




                                                                        PPPPaaaaggggeeee 3333






PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR((((1111))))                                                        PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR((((1111))))



     7.   Finally each specification is terminated with an optional set of
          instance names, to restrict the scope of the preceding
          specification.  The set of instance names is a ``[''. followed by a
          list of one or more space (or comma) separated names, numbers or
          strings, and a closing ``]''.  Elements in the list that are numbers
          are assumed to be internal instance identifiers, other elements are
          assumed to be external instance identifiers - see ppppmmmmGGGGeeeettttIIIInnnnDDDDoooommmm(3) for
          more information.
          If no instances are given, then the logging specification is applied
          to all instances of the associated metric(s), as of the time that
          the specification is processed.

     8.   There may be an arbitrary number of logging specifications.

     9.   Following all of the logging specifications, there may be an
          optional access control section, introduced by the literal token
          [[[[aaaacccccccceeeessssssss]]]].  Thereafter come access control rules of the form ``aaaalllllllloooowwww
          _h_o_s_t_l_i_s_t :::: _o_p_e_r_a_t_i_o_n ;;;;'' and ``ddddiiiissssaaaalllllllloooowwww _h_o_s_t_l_i_s_t :::: _o_p_e_r_a_t_i_o_n ;;;;''.
          The base _o_p_e_r_a_t_i_o_n_s are aaaaddddvvvviiiissssoooorrrryyyy, mmmmaaaannnnddddaaaattttoooorrrryyyy and eeeennnnqqqquuuuiiiirrrreeee.  In all
          other aspects, these access control statements follow the syntactic
          and semantic rules defined for the access control mechanisms used by
          PMCD and fully documented in ppppmmmmccccdddd(1).

EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
     For each PCP utility, there is a sample ppppmmmmllllooooggggggggeeeerrrr configuration file that
     could be used to create an archive log suitable for replaying with that
     tool (i.e. includes all of the performance metrics used by the tool).
     For a tool named _f_o_o this configuration file is located in
     /_v_a_r/_p_c_p/_c_o_n_f_i_g/_p_m_l_o_g_g_e_r/_c_o_n_f_i_g._f_o_o.

     The following is a simple default configuration file for a primary
     ppppmmmmllllooooggggggggeeeerrrr instance, and demonstrates most of the capabilities of the
     configuration specification language.

               log mandatory on once { hinv.ncpu hinv.ndisk }
               log mandatory on every 10 minutes {
                   irix.disk.all.write
                   irix.disk.all.read
                   irix.network.interface.in.packets [ "et0" ]
                   irix.network.interface.out.packets [ "et0" ]
                   irix.nfs.server.reqs [ "lookup" "getattr" "read" "write" ]
               }
               log advisory on every 30 minutes {
                   environ.temp
                   pmcd.pdu_in.total
                   pmcd.pdu_out.total
               }
               [access]
               disallow * : all except enquire;
               allow localhost : mandatory, advisory;


                                                                        PPPPaaaaggggeeee 4444






PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR((((1111))))                                                        PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR((((1111))))



AAAAUUUUTTTTOOOOMMMMAAAATTTTIIIICCCC RRRREEEESSSSTTTTAAAARRRRTTTT
     It is often useful for ppppmmmmllllooooggggggggeeeerrrr processes (other than the primary
     instance) to be started and stopped when the local host is booted or
     shutdown.  The script /_e_t_c/_i_n_i_t._d/_p_c_p_l_o_c_a_l and the necessary soft-links
     are provided, and can be modified by rrrrooooooootttt to run PCP tools automatically.
     If you want to find out more before starting, read the manual pages for
     rrrrcccc2222(1), rrrrcccc0000(1), sssshhhhuuuuttttddddoooowwwwnnnn(1) and the file /_e_t_c/_i_n_i_t._d/_R_E_A_D_M_E.

     For example, changing /_e_t_c/_i_n_i_t._d/_p_c_p_l_o_c_a_l so that it contains:

         # Add startup actions here
         (/usr/pcp/bin/cron.pmcheck &)
         ;;

         # Add shutdown actions here
         killall -INT pmlogger
         ;;

     will start ppppmmmmllllooooggggggggeeeerrrr instances at boot time and terminate them in an
     orderly fashion at system shutdown.

     This script runs as rrrrooooooootttt, so any _p_m_l_o_g_g_e_r instances it launches are also
     run as rrrrooooooootttt.  To run some ppppmmmmllllooooggggggggeeeerrrr instances as a particular user, create
     your own archive logger control file (see ccccrrrroooonnnn....ppppmmmmcccchhhheeeecccckkkk(1)) and use the
     ssssuuuu(1) command. e.g.

         # Add startup actions here
         (su debbie -c "/usr/pcp/bin/cron.pmcheck -c /usr/people/debbie/control" &)
         ;;

     at boot time will start the ppppmmmmllllooooggggggggeeeerrrr instances described in
     /_u_s_r/_p_e_o_p_l_e/_d_e_b_b_i_e/_c_o_n_t_r_o_l, running as user ddddeeeebbbbbbbbiiiieeee.

FFFFIIIILLLLEEEESSSS
     _a_r_c_h_i_v_e....mmmmeeeettttaaaa        metadata (metric descriptions, instance domains,
                         etc.) for the archive log
     _a_r_c_h_i_v_e....0000           initial volume of metrics values (subsequent volumes
                         have suffixes 1111, 2222, ...)
     _a_r_c_h_i_v_e....iiiinnnnddddeeeexxxx       temporal index to support rapid random access to the
                         other files in the archive log
     ////vvvvaaaarrrr////ttttmmmmpppp////ppppmmmmllllooooggggggggeeeerrrr   ppppmmmmllllooooggggggggeeeerrrr maintains the files in this directory as the
                         map between the process id of the ppppmmmmllllooooggggggggeeeerrrr instance
                         and the IPC port that may be used to control each
                         ppppmmmmllllooooggggggggeeeerrrr instance (as used by ppppmmmmllllcccc(1) and ppppmmmmvvvvccccrrrr(1))
     ////eeeettttcccc////ccccoooonnnnffffiiiigggg////ppppmmmmllllooooggggggggeeeerrrr
                         cccchhhhkkkkccccoooonnnnffffiiiigggg(1M) control flag, to control launching of
                         ppppmmmmllllooooggggggggeeeerrrr from ////eeeettttcccc////iiiinnnniiiitttt....dddd////ppppccccpppp
     ////eeeettttcccc////ccccoooonnnnffffiiiigggg////ppppmmmmllllooooggggggggeeeerrrr....ooooppppttttiiiioooonnnnssss
                         command line options to ppppmmmmllllooooggggggggeeeerrrr when launched from
                         ////eeeettttcccc////iiiinnnniiiitttt....dddd////ppppccccpppp





                                                                        PPPPaaaaggggeeee 5555






PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR((((1111))))                                                        PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR((((1111))))



     ////vvvvaaaarrrr////ppppccccpppp////ccccoooonnnnffffiiiigggg////ppppmmmmllllooooggggggggeeeerrrr////ccccoooonnnnffffiiiigggg....ddddeeeeffffaaaauuuulllltttt
                         default configuration file for the primary logger
                         instance launched from ////eeeettttcccc////iiiinnnniiiitttt....dddd////ppppccccpppp
     ////vvvvaaaarrrr////ppppccccpppp////ccccoooonnnnffffiiiigggg////ppppmmmmllllooooggggggggeeeerrrr////ccccoooonnnnffffiiiigggg....*
                         assorted configuration files suitable for creating
                         logs that may be subsequently replayed with the PCP
                         visualization and monitoring tools
     ////vvvvaaaarrrr////aaaaddddmmmm////ppppccccpppplllloooogggg////_h_o_s_t_n_a_m_e
                         Default directory for PCP archive files for
                         performance metric values collected from the host
                         _h_o_s_t_n_a_m_e.
     ./_p_m_l_o_g_g_e_r._l_o_g      (or $$$${{{{PPPPCCCCPPPP____LLLLOOOOGGGGDDDDIIIIRRRR----
                         ////vvvvaaaarrrr////aaaaddddmmmm////ppppccccpppplllloooogggg}}}}////_h_o_s_t_n_a_m_e////ppppmmmmllllooooggggggggeeeerrrr....lllloooogggg when started
                         automatically by either ////eeeettttcccc////iiiinnnniiiitttt....dddd////ppppccccpppp or one of the
                         ppppmmmmllllooooggggggggeeeerrrr(1) monitoring scripts such as
                         ccccrrrroooonnnn....ppppmmmmcccchhhheeeecccckkkk(1))
                         all messages and diagnostics are directed here
     ////eeeettttcccc////iiiinnnniiiitttt....dddd////ppppccccppppllllooooccccaaaallll
                         contains ``hooks'' to enable automatic restart at
                         system boot time

EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT
     Normally ppppmmmmllllooooggggggggeeeerrrr creates a socket to receive control messages from ppppmmmmllllcccc
     ((((1111)))) on the first available TCP/IP port numbered 4330 or higher.  The
     environment variable PPPPMMMMLLLLOOOOGGGGGGGGEEEERRRR____PPPPOOOORRRRTTTT may be used to specify an alternative
     starting port number.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     ppppmmmmccccdddd(1), ppppmmmmllllcccc(1), ppppmmmmdddduuuummmmpppplllloooogggg(1), ppppmmmmvvvvccccrrrr(1) and PPPPMMMMAAAAPPPPIIII(3).

DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     The archive logs are sufficiently precious that ppppmmmmllllooooggggggggeeeerrrr will not
     truncate an existing physical file.  A message of the form
             _pmLogNewFile: "foo.index" already exists, not over-written
             _pmLogCreate: No such file or directory
     indicates this situation has arisen.  You must explicitly remove the
     files and launch ppppmmmmllllooooggggggggeeeerrrr again.

     There may be at most one primary ppppmmmmllllooooggggggggeeeerrrr instance per monitored host;
     attempting to bend this rule produces the error:
             pmlogger: there is already a primary pmlogger running

     Various other messages relating to the creation and/or deletion of files
     in /_v_a_r/_t_m_p/_p_m_l_o_g_g_e_r suggest a permission problem on this directory, or
     some feral files have appeared therein.










                                                                        PPPPaaaaggggeeee 6666